Summary

• add transactional persisted sync metadata support across @tanstack/db, db-sqlite-persisted-collection-core, query-db-collection, and electric-db-collection
• persist row-scoped metadata with synced rows and collection-scoped metadata alongside persisted collection state
• use that metadata to preserve query ownership/retention across restart and to persist Electric resume state

How To Use

Custom sync implementations

If a collection is running on a persistence layer that supports this feature, the sync function now receives an optional metadata API alongside begin, write, commit, markReady, and truncate.

sync: ({ begin, write, commit, metadata }) => {
  const startupValue = metadata?.collection.get('my-sync:startup')

  begin()
  write({
    type: 'update',
    value: row,
    metadata: { source: 'remote' },
  })
  metadata?.collection.set('my-sync:startup', { ready: true })
  commit()
}

Available operations:

• metadata.row.get(key)
• metadata.row.set(key, value)
• metadata.row.delete(key)
• metadata.collection.get(key)
• metadata.collection.set(key, value)
• metadata.collection.delete(key)
• metadata.collection.list(prefix?)

Behavior:

• startup reads through get / list are allowed before any transaction is opened
• metadata writes are transactional and must happen inside begin() / commit()
• write({ metadata }) and metadata.row.set() target the same row metadata store

SQLite persisted collections

persistedCollectionOptions(...) now persists both row metadata and collection metadata when used with db-sqlite-persisted-collection-core.

Typical usage looks like:

const collection = createCollection(
  persistedCollectionOptions({
    ...someCollectionOptions,
    persistence: {
      adapter: sqliteAdapter,
    },
  }),
)

What you get automatically:

• row metadata hydrates with persisted rows
• collection metadata is loaded during startup before persisted sync work begins
• row data, row metadata, and collection metadata commit in the same persisted transaction

Query collections

Query collections can now retain persisted ownership metadata across restarts.

const collection = createCollection(
  persistedCollectionOptions({
    ...queryCollectionOptions({
      id: 'messages',
      queryClient,
      queryKey: ['messages', roomId],
      queryFn: fetchMessages,
      getKey: (row) => row.id,
      persistedGcTime: Number.POSITIVE_INFINITY,
    }),
    persistence: {
      adapter: sqliteAdapter,
    },
  }),
)

What this enables:

• row ownership is persisted on rows, so warm starts do not incorrectly delete disjoint pre-hydrated rows
• query retention is separate from in-memory TanStack Query gcTime
• persistedGcTime can be finite or effectively indefinite for offline-first flows
• when a retained query is requested again, reconciliation diffing uses that query's owned-row baseline instead of the whole collection

Electric collections

Electric collections now persist resume metadata at collection scope when wrapped with persisted collection options.

const collection = createCollection(
  persistedCollectionOptions({
    ...electricCollectionOptions({
      id: 'todos',
      getKey: (row) => row.id,
      shapeOptions: {
        url: electricUrl,
        params: { table: 'todos' },
      },
    }),
    persistence: {
      adapter: sqliteAdapter,
    },
  }),
)

What this enables:

• persisted startup can reuse a saved Electric offset / handle resume point
• resume metadata is committed transactionally with the batch that made it valid
• must-refetch/reset paths write a reset marker before reloading so restart does not resume from stale stream state

Test plan

• Run pnpm vitest --run packages/db/tests/collection.test.ts
• Run pnpm --filter @tanstack/query-db-collection exec vitest run tests/query.test.ts --coverage.enabled false
• Run pnpm --filter @tanstack/electric-db-collection exec vitest run tests/electric.test.ts --coverage.enabled false
• Run pnpm --filter @tanstack/db-sqlite-persisted-collection-core exec vitest run tests/persisted.test.ts tests/sqlite-core-adapter.test.ts --coverage.enabled false

Notes

• The persisted SQLite package tests are functionally green in package-local runs.
• There is still noisy stderr in some query tests from expected error-path coverage and existing cleanupQueryIfIdle warnings.